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 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 Options ¶
Options are per-call overrides shared by HTTP and WebSocket calls, the scripting-layer equivalent of protocol.Target's own option fields.
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 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).