netapi

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Oct 6, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CheckRecorder added in v0.4.0

type CheckRecorder interface {
	RecordCheck(name string, passed bool)
}

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

type Dataset interface {
	Next() map[string]any
	Random() map[string]any
	Len() int
}

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

type HTTPResponse struct {
	StatusCode int
	Headers    http.Header
	Body       []byte
}

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 Options

type Options struct {
	Headers            map[string]string
	InsecureSkipVerify bool
}

Options are per-call overrides shared by HTTP and WebSocket calls, the scripting-layer equivalent of protocol.Target's own option fields.

type SafetyCheck

type SafetyCheck func(host string) error

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 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

func (c *WSConn) Close() error

Close closes the connection, sending a normal-closure frame on a best-effort basis first. Safe to call more than once.

func (*WSConn) Receive

func (c *WSConn) Receive(ctx context.Context) (data []byte, closed bool, err error)

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).

func (*WSConn) Send

func (c *WSConn) Send(ctx context.Context, data []byte, text bool) error

Send writes one message. text selects a text frame (as opposed to binary) -- scripts sending JSON, the common case, want text.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL