pluginsdk

type Call struct {
	Step string
	// Session is the value NewSession returned for this virtual user.
	Session   any
	VU        int64
	Iteration int64
	// Config is the step's rendered config, a JSON object that has passed
	// the step's schema.
	Config json.RawMessage
	// Timeout is the step's timeout; ctx carries the same deadline.
	Timeout time.Duration
	// Traceparent and Baggage are W3C trace context for this step, for
	// protocols that can carry it (message headers, metadata).
	Traceparent string
	Baggage     string
}

type Error struct {
	Class string
	Err   error
}

type GRPCPlugin struct {
	plugin.NetRPCUnsupportedPlugin
	// Impl is the plugin's implementation; nil on the host side.
	Impl pluginv1.PluginServiceServer
}

type Phases struct {
	DNS, Connect, TLS time.Duration
	// Wait is the time from sending to the first byte of the reply.
	Wait time.Duration
	// Download is the time spent reading the reply.
	Download time.Duration
	// FirstEvent is the time from the start of a streaming step to its
	// first message.
	FirstEvent time.Duration
}

type Plugin struct {
	// Name is used in scenarios (mqtt in mqtt.publish) and in the
	// executable's name (stampede-plugin-mqtt): lowercase letters, digits
	// and hyphens, starting with a letter.
	Name string
	// Version is the plugin's own version, such as 0.1.0.
	Version     string
	Description string
	Steps       []Step
	// NewSession creates the state of one virtual user: its connection or
	// client. Every step the user runs receives it as Call.Session. If the
	// value implements io.Closer it is closed when the user retires. Nil
	// gives every user a nil session.
	NewSession func(ctx context.Context, info SessionInfo) (any, error)
}

type Result struct {
	// Latency is the step's duration. Zero means the SDK uses how long Run
	// took.
	Latency time.Duration
	// Phases break the latency down where meaningful.
	Phases Phases
	// BytesIn and BytesOut count payload bytes received and sent.
	BytesIn, BytesOut int64
	// Values is what the step returned, marshalled to a JSON object
	// (a map or a struct). Scenario checks and extractors read it:
	// extract: { id: "$.messageId" }.
	Values any
	// Events counts messages a streaming step received. With
	// Phases.FirstEvent set the step is reported like a stream: time to
	// first message and messages per second.
	Events int64
	// Skipped means there was nothing to do (connect on a session that is
	// already connected): Stampede records no sample for the step.
	Skipped bool
}

type SessionInfo struct {
	// VU is unique within a run.
	VU    int64
	RunID string
}

type Step struct {
	// Name is the step's name within the plugin (publish in mqtt.publish):
	// letters, digits, underscores and hyphens, starting with a letter.
	Name        string
	Description string
	// Schema is a JSON Schema (draft 2020-12) for the step's config, the
	// `with:` block of a scenario step. Stampede checks scenarios against
	// it when they are loaded, and the SDK checks every rendered config
	// before Run sees it. Mark the top-level property holding the address
	// the step connects to with "x-stampede-target": true so Stampede can
	// apply its target policy to it.
	Schema string
	// Run executes the step. A returned error fails the step; use Fail to
	// give it an error class. Run is called concurrently for different
	// sessions, never for the same one.
	Run func(ctx context.Context, c *Call) (*Result, error)
}