api

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 8, 2022 License: MIT Imports: 10 Imported by: 1

Documentation

Index

Constants

View Source 
const CurrentAPIVersion uint32 = 5

CurrentAPIVersion is the current version of the API that the clients must be able to speak in order to communicate with the server. Versioning starts at 1, while 0 is to be considered an error indicator.

Variables

View Source 
var DefaultEventTimeout = 3 * time.Second

DefaultEventTimeout is the default time to wait for sending or receiving an event on the events channel.

View Source 
var ResponseTypeToName = map[ResponseType]string{
	ResponseTypeStart:   "ResponseTypeStart",
	ResponseTypeStop:    "ResponseTypeStop",
	ResponseTypeStatus:  "ResponseTypeStatus",
	ResponseTypeRetry:   "ResponseTypeRetry",
	ResponseTypeVersion: "ResponseTypeVersion",
	ResponseTypeList:    "ResponseTypeList",
}

ResponseTypeToName maps response types to their names.

Functions

This section is empty.

Types

type API 

type API struct {
	// Config is a set of knobs to change the behavior of API processing.
	Config Config
	// Events channel is used to route API events between clients and the
	// JobManager. It is not necessary to close it explicitly as it will be
	// garbage-collected when the API structure in the client goes out of scope.
	Events chan *Event
	// contains filtered or unexported fields
}

The API structure implements the communication between clients and the JobManager. It enables several operations like starting, stopping, retrying a job, and getting a job status.

func New 

func New(opts ...Option) (*API, error)

New returns an initialized instance of an API struct with the specified server ID generation function.

func (*API) List 

func (a *API) List(ctx xcontext.Context, requestor EventRequestor, query *storage.JobQuery) (Response, error)

List will list jobs matching the specified criteria.

func (*API) Retry 

func (a *API) Retry(ctx xcontext.Context, requestor EventRequestor, jobID types.JobID) (Response, error)

Retry will retry a job identified by its ID, using the same job description. If the job is still running, an error is returned.

func (*API) SendEvent 

func (a *API) SendEvent(ev *Event, timeout *time.Duration) error

SendEvent sends an Event object on the event channel, without waiting for a reply. If the send doesn't complete within the timeout, an error is returned.

func (*API) SendReceiveEvent 

func (a *API) SendReceiveEvent(ev *Event, timeout *time.Duration) (*EventResponse, error)

SendReceiveEvent sends an Event object on the event channel, and waits for a reply from the consumer. The timeout is used once for the send, and once for the receive, it's not a cumulative timeout.

func (API) ServerID 

func (a API) ServerID() string

ServerID returns the Server ID to be used in responses. A custom server ID generation function can be passed to New().

func (*API) Start 

func (a *API) Start(ctx xcontext.Context, requestor EventRequestor, jobDescriptor string) (Response, error)

Start requests to create a new test job, as described by the job descriptor. A job descriptor may contain multiple tests, which will be run sequentially, not in parallel. If you need parallelism, you need to submit multiple independent jobs. If you need coordination across jobs, you need to write your own synchronization plugins that use external means (e.g. the events API), but no inter-job synchronization is implemented in the framework itself. This is intentional, to avoid overcomplicating the orchestration for a few edge cases. Each job descriptor must be JSON-encoded, and will be deserialized in a `contest.JobDescriptor` object by the JobManager. This method must return a unique job ID, that can be used for various operations via the API, e.g. getting the job status or stopping it. This method should return an error if the job description is malformed or invalid, and if the API version is incompatible.

func (*API) Status 

func (a *API) Status(ctx xcontext.Context, requestor EventRequestor, jobID types.JobID) (Response, error)

Status polls the status of a job by its ID, and returns a contest.Status object

func (*API) Stop 

func (a *API) Stop(ctx xcontext.Context, requestor EventRequestor, jobID types.JobID) (Response, error)

Stop requests a job cancellation by the given job ID.

func (API) Version 

func (a API) Version() Response

Version returns the version of the API. It's the client's responsibility to check whether it can talk the right API. If the client speaks an incompatible version of the API that the server doesn't understand, it's the server's responsibility to return an error upon API calls.

type Config 

type Config struct {
	// EventTimeout defines time duration for API request to be processed.
	// If a request is not processed in time, then an error is returned to the
	// client.
	EventTimeout time.Duration

	// ServerIDFunc defines a custom server ID in API responses.
	ServerIDFunc ServerIDFunc
}

Config is a set of knobs to change the behavior of API processing. In other words, Config aggregates all the Option-s into one structure.

type Event 

type Event struct {
	Context  xcontext.Context
	Type     EventType
	ServerID string
	Err      error
	Msg      EventMsg
	// RespCh is a channel where the JobManager can send the responses back to
	// what generated the event. E.g. if a job status is requested, the answer
	// goes back to the caller in an EventResponse via this channel.
	RespCh chan *EventResponse
}

Event represents an event that the API can generate. This is used by the API listener to enable event handling.

type EventListMsg 

type EventListMsg struct {
	Query *storage.JobQuery
	// contains filtered or unexported fields
}

EventListMsg contains the arguments for an event of type List.

func (EventListMsg) Requestor 

func (e EventListMsg) Requestor() EventRequestor

Requestor returns the requestor of the API call as reported by the client.

type EventListResponse 

type EventListResponse struct {
	Requestor EventRequestor
	Jobs      []types.JobID
	Err       error
}

EventListResponse is a response to EventListMsg.

type EventMsg 

type EventMsg interface {
	Requestor() EventRequestor
}

EventMsg defines various event messages for different event types. Error events have no associated message, the error information is set in the Err attribute.

type EventRequestor 

type EventRequestor string

EventRequestor identifies who is sending a request. This is set on the client side, but can be validated and overridden in the listener if necessary. This is *not* authentication, it's just the client declaring who they are, and obviously clients can change this field to whatever they want.

type EventResponse 

type EventResponse struct {
	Requestor EventRequestor
	JobID     types.JobID
	Err       error
	Status    *job.Status
	JobIDs    []types.JobID
}

EventResponse is a response to an EventMsg.

type EventRetryMsg 

type EventRetryMsg struct {
	JobID types.JobID
	// contains filtered or unexported fields
}

EventRetryMsg contains the arguments for an event of type Retry.

func (EventRetryMsg) Requestor 

func (e EventRetryMsg) Requestor() EventRequestor

Requestor returns the requestor of the API call as reported by the client.

type EventStartMsg 

type EventStartMsg struct {
	TestID        string
	NumRuns       uint32
	JobDescriptor string
	// contains filtered or unexported fields
}

EventStartMsg contains the arguments for an event of type Start.

func (EventStartMsg) Requestor 

func (e EventStartMsg) Requestor() EventRequestor

Requestor returns the requestor of the API call as reported by the client.

type EventStatusMsg 

type EventStatusMsg struct {
	JobID types.JobID
	// contains filtered or unexported fields
}

EventStatusMsg contains the arguments for an event of type Status.

func (EventStatusMsg) Requestor 

func (e EventStatusMsg) Requestor() EventRequestor

Requestor returns the requestor of the API call as reported by the client.

type EventStopMsg 

type EventStopMsg struct {
	JobID types.JobID
	// contains filtered or unexported fields
}

EventStopMsg contains the arguments for an event of type Stop.

func (EventStopMsg) Requestor 

func (e EventStopMsg) Requestor() EventRequestor

Requestor returns the requestor of the API call as reported by the client.

type EventType 

type EventType uint16

EventType identifies an API event type. 

const (
	EventTypeStart EventType = iota
	EventTypeStatus
	EventTypeStop
	EventTypeRetry
	EventTypeError
	EventTypeList
)

list of existing API event types.

func (EventType) String 

func (e EventType) String() string

type ListResponse 

type ListResponse struct {
	ServerID string
	Data     ResponseDataList
	Err      *xjson.Error
}

ListResponse is a typesafe version of Response with a List payload

type Listener 

type Listener interface {
	// Serve is responsible for starting the listener and calling the API
	// methods to communicate with the JobManager.
	// The channel is used for cancellation, which can be called by the
	// JobManager and should be handled by the listener to do a graceful
	// shutdown.
	Serve(xcontext.Context, *API) error
}

Listener defines the interface for an API listener. This is used to implement different API transports, like thrift, or gRPC.

type Option 

type Option interface {
	Apply(*Config)
}

Option is an additional argument to method New to change the behavior of API processing.

type OptionEventTimeout 

type OptionEventTimeout time.Duration

OptionEventTimeout defines time duration for API request to be processed. If a request is not processed in time, then an error is returned to the client.

func (OptionEventTimeout) Apply 

func (opt OptionEventTimeout) Apply(config *Config)

Apply implements Option.

type OptionServerID 

type OptionServerID string

OptionServerID defines a custom server ID in API responses.

func (OptionServerID) Apply 

func (opt OptionServerID) Apply(config *Config)

Apply implements Option.

type Response 

type Response struct {
	ServerID string
	Type     ResponseType
	Data     ResponseData
	Err      error
}

Response is the type returned to any API request.

type ResponseData 

type ResponseData interface {
	Type() ResponseType
}

ResponseData is the interface type implemented by the various response types.

type ResponseDataList 

type ResponseDataList struct {
	JobIDs []types.JobID
}

ResponseDataList is the response type for a List request.

func (ResponseDataList) Type 

func (r ResponseDataList) Type() ResponseType

Type returns the response type.

type ResponseDataRetry 

type ResponseDataRetry struct {
	JobID    types.JobID
	NewJobID types.JobID
}

ResponseDataRetry is the response type for a Retry request.

func (ResponseDataRetry) Type 

func (r ResponseDataRetry) Type() ResponseType

Type returns the response type.

type ResponseDataStart 

type ResponseDataStart struct {
	JobID types.JobID
}

ResponseDataStart is the response type for a Start request.

func (ResponseDataStart) Type 

func (r ResponseDataStart) Type() ResponseType

Type returns the response type.

type ResponseDataStatus 

type ResponseDataStatus struct {
	Status *job.Status
}

ResponseDataStatus is the response type for a Status request.

func (ResponseDataStatus) Type 

func (r ResponseDataStatus) Type() ResponseType

Type returns the response type.

type ResponseDataStop 

type ResponseDataStop struct {
}

ResponseDataStop is the response type for a Stop request.

func (ResponseDataStop) Type 

func (r ResponseDataStop) Type() ResponseType

Type returns the response type.

type ResponseDataVersion 

type ResponseDataVersion struct {
	Version uint32
}

ResponseDataVersion is the response type for a Version request.

func (ResponseDataVersion) Type 

func (r ResponseDataVersion) Type() ResponseType

Type returns the response type.

type ResponseType 

type ResponseType int32

ResponseType defines the storage type of a response type. 

const (
	ResponseTypeStart ResponseType = iota
	ResponseTypeStop
	ResponseTypeStatus
	ResponseTypeRetry
	ResponseTypeVersion
	ResponseTypeList
)

The various response types used in the Response struct.

type RetryResponse 

type RetryResponse struct {
	ServerID string
	Data     ResponseDataRetry
	Err      *xjson.Error
}

RetryResponse is a typesafe version of Response with a Status payload

type ServerIDFunc 

type ServerIDFunc func() string

ServerIDFunc is used to return a custom server ID in api responses.

type StartResponse 

type StartResponse struct {
	ServerID string
	Data     ResponseDataStart
	Err      *xjson.Error
}

StartResponse is a typesafe version of Response with a Status payload

type StatusResponse 

type StatusResponse struct {
	ServerID string
	Data     ResponseDataStatus
	Err      *xjson.Error
}

StatusResponse is a typesafe version of Response with a Status payload

type StopResponse 

type StopResponse struct {
	ServerID string
	Data     ResponseDataStop
	Err      *xjson.Error
}

StopResponse is a typesafe version of Response with a Status payload

type VersionResponse 

type VersionResponse struct {
	ServerID string
	Data     ResponseDataVersion
	Err      *xjson.Error
}

VersionResponse is a typesafe version of Response with a Status payload

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.