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 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 bots.cfg config.

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 Request

type Request struct {
	BotID               string                 // validated bot ID
	SessionID           string                 // validated RBE bot session ID, if present
	SessionTokenExpired bool                   // true if the request has expired session token
	PollState           *internalspb.PollState // validated poll state
	Dimensions          map[string][]string    // validated dimensions
}

Request is extracted from an authenticated request from a bot.

type RequestBody

type RequestBody interface {
	ExtractPollToken() []byte               // the poll token, if present
	ExtractSessionToken() []byte            // the session token, if present
	ExtractDimensions() map[string][]string // dimensions reported by the bot, if present
	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, projectID string, hmacSecret *hmactoken.Secret) *Server

New constructs new Server.