botsrv

Documentation

Overview

Package botsrv knows how to handle calls from Swarming bots.

Index

• func AuthorizeBot(ctx context.Context, botID string, methods []*configpb.BotAuth) error
• func GET(s *Server, route string, handler router.Handler)
• func JSON[B any, RB RequestBodyConstraint[B]](s *Server, route string, h Handler[B])
• type Handler
• type KnownBotInfo
• type KnownBotProvider
• type Request
• type RequestBody
• type RequestBodyConstraint
• type Response
• type Server
  • func New(ctx context.Context, cfg *cfg.Provider, r *router.Router, prx *pyproxy.Proxy, ...) *Server

Functions

func AuthorizeBot

func AuthorizeBot(ctx context.Context, botID string, methods []*configpb.BotAuth) error

AuthorizeBot checks the bot credentials in the context match requirements from bots.cfg for this bot based on its ID.

Returns no error if the bot is successfully authorized, a fatal error if not, and a transient-tagged error if there was some unexpected error. A fatal error message will be returned to the caller as is and should not contain any internal details not already available to the caller.

Logs errors inside.

func GET

func GET(s *Server, route string, handler router.Handler)

GET installs a GET request handler.

It authenticates the bot or user credentials (if any), but doesn't itself check bots.cfg authorization rules. Call AuthorizeBot to do that.

It additionally applies traffic routing rules to send a portion of requests to the Python server.

func JSON

func JSON[B any, RB RequestBodyConstraint[B]](s *Server, route string, h Handler[B])

JSON installs a bot API request handler at the given route.

This is a POST handler that receives JSON-serialized B and replies with some JSON-serialized response.

It performs bot authentication and authorization based on the bot session token and the bot state in the datastore.

Types

type Handler

type Handler[B any] func(ctx context.Context, body *B, req *Request) (Response, error)

Handler handles an authenticated request from a bot.

It takes a raw deserialized request body and all authenticated data extracted from it.

It returns a response that will be serialized and sent to the bot as JSON or a gRPC error code that will be converted into an HTTP error.

type KnownBotInfo

type KnownBotInfo struct {
	// SessionID is the current bot session ID of this bot.
	SessionID string
	// Dimensions is "k:v" dimensions registered by this bot in the last poll.
	Dimensions []string
}

KnownBotInfo is information about a bot registered in the datastore.

type KnownBotProvider

type KnownBotProvider func(ctx context.Context, botID string) (*KnownBotInfo, error)

KnownBotProvider knows how to return information about existing bots.

Returns nil and no error if the bot is not registered in the datastore. All other errors can be considered transient.

type Request

type Request struct {
	Session    *internalspb.Session   // the bot session from the session token
	Dimensions []string               // bot's "k:v" dimensions as stored in the datastore
	PollState  *internalspb.PollState // validated poll state, TODO: delete
}

Request is extracted from an authenticated request from a bot.

type RequestBody

type RequestBody interface {
	ExtractSession() []byte      // the token with bot Session proto
	ExtractPollToken() []byte    // the poll token, if present, TODO: delete
	ExtractSessionToken() []byte // the RBE session token, if present, TODO: delete
	ExtractDebugRequest() any    // serialized as JSON and logged on errors
}

RequestBody should be implemented by a JSON-serializable struct representing format of some particular request.

type RequestBodyConstraint

type RequestBodyConstraint[B any] interface {
	RequestBody
	*B
}

RequestBodyConstraint is needed to make Go generics type checker happy.

type Response

type Response any

Response is serialized as JSON and sent to the bot.

type Server

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

Server knows how to authenticate bot requests and route them to handlers.

func New

func New(ctx context.Context, cfg *cfg.Provider, r *router.Router, prx *pyproxy.Proxy, bots KnownBotProvider, projectID string, hmacSecret *hmactoken.Secret) *Server

New constructs new Server.