Documentation
¶
Overview ¶
Package netapi gives VegaLoad's scripting runtimes (internal/scripting/js and /python) the real HTTP and WebSocket access FR-CLI-08 asks for: a scenario script can make an actual network call and read the response (status, headers, body) back into the script, unlike internal/protocol's drivers, which exist to repeat one fixed Target and discard the response body entirely -- see protocol.Result's doc comment, and http1.Driver.Do, which io.Copy's the body straight to io.Discard. Without the body coming back, a script has nothing to carry from one call into the next, which is the entire point of FR-CLI-08.
netapi knows nothing about JavaScript or Python: js.go and python.go are responsible for presenting these types in whatever shape their language needs (a goja.Object for JS; a proxied RPC call for Python, whose subprocess can't hold a Go value at all). It also knows nothing about FR-CLI-06's allowlist policy itself -- SafetyCheck is a hook the caller (cmd/vegaload) supplies, so the policy decision lives in one place (internal/safety) and this package only ever enforces whatever decision it's given.
Index ¶
- func ProtoFunctions() map[string][]string
- func RunEnded(ctx context.Context) bool
- type CheckRecorder
- type Dataset
- type HTTPClient
- type HTTPResponse
- type Inputs
- type KafkaRecord
- type Options
- type ProtoCall
- type ProtoClient
- func (c *ProtoClient) Call(ctx context.Context, name string, call ProtoCall) (*ProtoReply, error)
- func (c *ProtoClient) Close()
- func (c *ProtoClient) GRPC(ctx context.Context, call ProtoCall) (*ProtoReply, error)
- func (c *ProtoClient) Kafka(ctx context.Context, mode string, call ProtoCall) (*ProtoReply, error)
- func (c *ProtoClient) MQTT(ctx context.Context, mode string, call ProtoCall) (*ProtoReply, error)
- func (c *ProtoClient) TCP(ctx context.Context, call ProtoCall) (*ProtoReply, error)
- func (c *ProtoClient) UDP(ctx context.Context, call ProtoCall) (*ProtoReply, error)
- type ProtoMessage
- type ProtoReply
- type SafetyCheck
- type StepRecorder
- type WSConn
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ProtoFunctions ¶ added in v0.6.0
ProtoFunctions lists the calls a script can make, by namespace: tcp.send, mqtt.publish and so on. Each scripting language builds its globals from this list, so they cannot differ.
func RunEnded ¶ added in v0.6.0
RunEnded reports whether the run is over: ctx is done, or its deadline has passed. The timer that cancels a ctx at its deadline can fire a few milliseconds late, and ctx.Err() stays nil until it does. Scripts use this to tell a call that was cut off by the end of the run from a real failure, in that gap too.
Types ¶
type CheckRecorder ¶ added in v0.4.0
CheckRecorder receives the outcome of every check a scenario script makes (FR-CLI-12): the check's name and whether it passed. The report Collector implements it. A nil recorder is allowed everywhere it is accepted, and means checks are evaluated but not counted.
type Dataset ¶ added in v0.4.0
Dataset is one data file's rows. Next hands out the rows in order, one per call, shared by all virtual users, and starts over after the last. Random returns any row. Rows are read-only to the script.
type HTTPClient ¶
type HTTPClient struct {
// contains filtered or unexported fields
}
HTTPClient is one VU's HTTP client: one underlying *http.Client (and its connection pool) reused across every call for the life of the VU, the same keep-alive behaviour internal/protocol/http1.Driver gives a fixed target, just now available for a script's own ad hoc URLs.
func NewHTTPClient ¶
func NewHTTPClient(check SafetyCheck, timeout time.Duration) *HTTPClient
NewHTTPClient returns an HTTPClient that runs check (if non-nil) against every call's target host before connecting. timeout bounds each individual request the same way protocol/http1.New's timeout does; 0 means no per-request timeout beyond the context passed to Do.
func (*HTTPClient) Close ¶
func (c *HTTPClient) Close()
Close releases the client's idle connections. Safe to call even if no request was ever made.
func (*HTTPClient) Do ¶
func (c *HTTPClient) Do(ctx context.Context, method, rawURL string, body []byte, opts Options) (*HTTPResponse, error)
Do performs one HTTP request. method defaults to GET if empty; body may be nil. opts.InsecureSkipVerify, when set, uses a dedicated one-shot transport for this call rather than mutating the client's shared one, since a script may hit several hosts with different TLS needs across one iteration.
type HTTPResponse ¶
HTTPResponse is what one HTTPClient.Do call hands back to a script -- enough to inspect a status, read a header, and -- the entire point of FR-CLI-08 -- parse a body to carry a value into the next call.
type Inputs ¶ added in v0.4.0
type Inputs interface {
// Env returns the value of an exposed environment variable.
Env(name string) (string, bool)
// EnvNames lists the exposed variable names.
EnvNames() []string
// Dataset returns the data file registered under name.
Dataset(name string) (Dataset, bool)
// DatasetNames lists the registered data file names.
DatasetNames() []string
}
Inputs is what a scenario script can read from outside itself (FR-CLI-17): environment variables the run was told to expose, and data files that feed rows to virtual users. The cmd layer builds it from the run's flags; a nil Inputs means the script can read nothing, so `env` is empty and `data` has no files.
type KafkaRecord ¶ added in v0.6.0
KafkaRecord is one Kafka record a call produced or read.
type Options ¶
Options are per-call overrides shared by HTTP and WebSocket calls, the scripting-layer equivalent of protocol.Target's own option fields.
type ProtoCall ¶ added in v0.6.0
type ProtoCall struct {
// URL is the target. tcp and udp accept a bare host:port too.
URL string
// Body is the data to send.
Body []byte
// Options are the driver's own options, the same keys as -opt.
Options map[string]string
// Insecure turns off TLS certificate checks.
Insecure bool
// Timeout bounds the whole call. Zero means the client's default.
Timeout time.Duration
// Password is the MQTT password. nil means none. A script passes it
// here, from `env`, so it never has to be put in Options.
Password *string
// Headers are the gRPC metadata of a grpc.call.
Headers map[string]string
}
ProtoCall is one call a script makes to a tcp, udp, mqtt, kafka or grpc target.
func ProtoCallFromArgs ¶ added in v0.6.0
ProtoCallFromArgs builds a call from a target and the options object a script passed. body, insecure, timeout and password are the script's own keys. For kafka, value is the same as body. Every other key becomes a driver option, and the driver rejects the ones it does not know. A trailing underscore is dropped from a key, so a language where a word such as "from" is reserved can write from_.
type ProtoClient ¶ added in v0.6.0
type ProtoClient struct {
// contains filtered or unexported fields
}
ProtoClient makes tcp, udp and mqtt calls for one VU. Each call opens its own connection, the same as the load-test drivers do, so the client holds no connection, except the Kafka clients that Close releases.
func NewProtoClient ¶ added in v0.6.0
func NewProtoClient(check SafetyCheck, timeout time.Duration) *ProtoClient
NewProtoClient returns a ProtoClient. check, when not nil, is run on the host of every call before it connects. timeout is the default for a call.
func (*ProtoClient) Call ¶ added in v0.6.0
func (c *ProtoClient) Call(ctx context.Context, name string, call ProtoCall) (*ProtoReply, error)
Call makes the call that name says, such as "tcp.send" or "kafka.admin".
func (*ProtoClient) Close ¶ added in v0.6.0
func (c *ProtoClient) Close()
Close closes the Kafka and gRPC clients. Safe to call more than once.
func (*ProtoClient) GRPC ¶ added in v0.6.0
func (c *ProtoClient) GRPC(ctx context.Context, call ProtoCall) (*ProtoReply, error)
GRPC makes one unary gRPC call. Its connection is kept for the next call to the same target, as a real client keeps its channel.
func (*ProtoClient) Kafka ¶ added in v0.6.0
func (c *ProtoClient) Kafka(ctx context.Context, mode string, call ProtoCall) (*ProtoReply, error)
Kafka does one Kafka job. mode is produce, consume, roundtrip or admin. The client is kept for the next call with the same connection options.
func (*ProtoClient) MQTT ¶ added in v0.6.0
func (c *ProtoClient) MQTT(ctx context.Context, mode string, call ProtoCall) (*ProtoReply, error)
MQTT does one mqtt job. mode is publish, subscribe or roundtrip.
func (*ProtoClient) TCP ¶ added in v0.6.0
func (c *ProtoClient) TCP(ctx context.Context, call ProtoCall) (*ProtoReply, error)
TCP sends over one TCP connection and reads the reply the options ask for.
func (*ProtoClient) UDP ¶ added in v0.6.0
func (c *ProtoClient) UDP(ctx context.Context, call ProtoCall) (*ProtoReply, error)
UDP sends one datagram, and waits for a reply if the options ask for it.
type ProtoMessage ¶ added in v0.6.0
ProtoMessage is one MQTT message a call received.
type ProtoReply ¶ added in v0.6.0
type ProtoReply struct {
OK bool
Error string
BytesSent int64
BytesReceived int64
// Body is the reply read from a tcp or udp target. It is set even when
// the call failed after some bytes came in.
Body []byte
// Messages are the messages an mqtt subscribe or roundtrip received.
Messages []ProtoMessage
// IsKafka is true for a Kafka reply, the only one with Records and Text.
IsKafka bool
// Records are the records a kafka produce, consume or roundtrip
// wrote or read. For produce, Partition and Offset say where the broker
// stored each one.
Records []KafkaRecord
// Text is the answer of a kafka admin action.
Text string
// IsGRPC is true for a gRPC reply. Body is then the reply as JSON text
// (or base64), JSON is that text parsed, and GRPCStatus is the status
// code, 0 when the call worked.
IsGRPC bool
GRPCStatus int
GRPCStatusName string
JSON any
}
ProtoReply is what a call hands back. A call that fails on the network (refused, timed out, no reply) is a reply with OK false and Error set, not a Go error: a script is expected to look at it.
func (*ProtoReply) Fields ¶ added in v0.6.0
func (r *ProtoReply) Fields() map[string]any
Fields is the reply as plain data: the shape a script sees. body is the reply of tcp and udp (and of grpc, as JSON text, with json holding it parsed, and status and statusName for the gRPC code). messages is for mqtt, each {topic, body}. kafka adds records (each {topic, partition, offset, key, value}) and text. error is "" when the call worked.
type SafetyCheck ¶
SafetyCheck is called with the bare host netapi is about to connect to, before every HTTP request and WebSocket dial. Returning a non-nil error refuses the call; the caller (cmd/vegaload) builds this from FR-CLI-06's allowlist and the run's -yes/-allow-target flags, enforced per call since a scripted target is only known once the script runs -- see run.go's doc comment for why that differs from protocol-direct mode's one pre-run check.
A nil SafetyCheck allows every host unchecked; HTTPClient and Dial treat it that way, so a test (or a future caller with no policy of its own) doesn't have to supply a no-op function.
type StepRecorder ¶ added in v0.6.0
StepRecorder receives every named step a scenario script runs (FR-CLI-18): the step's name, how long it took, and whether it failed. The report Collector implements it. A nil recorder is allowed everywhere it is accepted, and means steps still run but are not counted.
type WSConn ¶
type WSConn struct {
// contains filtered or unexported fields
}
WSConn is one open WebSocket connection, kept alive across multiple Send/Receive calls -- unlike internal/protocol/websocket.Driver, which opens, sends at most one message, reads at most one reply, and closes again on every single Do call. FR-CLI-08's own example (read frames until a flow completes or aborts) needs exactly this: a connection a script can read from repeatedly.
func Dial ¶
func Dial(ctx context.Context, check SafetyCheck, rawURL string, timeout time.Duration, opts Options) (*WSConn, error)
Dial opens a WebSocket connection to rawURL (ws:// or wss://), after running check against its host. timeout bounds the handshake only -- Receive has no deadline of its own unless the caller gives one, since a long-lived connection reading many frames shouldn't inherit a one-shot handshake budget.
func (*WSConn) Close ¶
Close closes the connection, sending a normal-closure frame on a best-effort basis first. Safe to call more than once.
func (*WSConn) Receive ¶
Receive waits for the next message and returns its payload. closed is true, with a nil error, on a normal close -- so a script's "read frames until it completes" loop can just check for that instead of treating the expected end of the stream as an error. A non-nil error means something other than a clean close: a read past ctx's deadline, or a protocol error.
Receive honors ctx's deadline if it has one; otherwise it blocks until a message arrives, the connection closes, or ctx is cancelled for some other reason (the run ending).