Package org.microproxy

Interface ScriptCallObserver

public interface ScriptCallObserver

Sees every call into a script's hooks (with the optional Starlark module): when it starts, and how it ended, with the interpreter steps it ran, about how many bytes of values it created, how long it took and why it failed. It is the place for tracing to make a span of each call, as a child of its exchange's. Register one with HttpProxyServerBootstrap.withScriptCallObserver(org.microproxy.ScriptCallObserver) (the --script option passes it on to the script) or the script's builder.

Calls come from the proxy's threads, at the same time for different exchanges (and for the two directions of a tunnel), so implementations must be thread-safe; they run inside the hook call, so they must be quick and must not throw. Without an observer the proxy calls nothing.

Field Summary

Fields

Modifier and Type	Field	Description
static final ScriptCallObserver	NOOP	Sees nothing.

Method Summary

Modifier and Type	Method	Description
default void	onCallEnd(Object token, String hook, String script, FlowContext flow, long steps, long allocBytes, long nanos, String budgetExceeded, Throwable error)	A call has ended.
default Object	onCallStart(String hook, String script, FlowContext flow)	A call is starting.

Field Details

NOOP

static final ScriptCallObserver NOOP

Sees nothing.

Method Details

onCallStart

default Object onCallStart(String hook,
 String script,
 FlowContext flow)

A call is starting.

Parameters:

hook - the function called: on_request, on_response, on_frame, on_tcp_message, ...

script - the script's name, as its stats are tagged

flow - the exchange the call is for (the tunnel's or flow's, for TCP, UDP and QUIC hooks), or null when the hook has none (upstream, a QUIC framer)

Returns:

a value handed back to onCallEnd(java.lang.Object, java.lang.String, java.lang.String, org.microproxy.FlowContext, long, long, long, java.lang.String, java.lang.Throwable) (a span, say), or null

onCallEnd

default void onCallEnd(Object token,
 String hook,
 String script,
 FlowContext flow,
 long steps,
 long allocBytes,
 long nanos,
 String budgetExceeded,
 Throwable error)

A call has ended.

Parameters:

token - what onCallStart(java.lang.String, java.lang.String, org.microproxy.FlowContext) returned for the call

hook - the function called

script - the script's name

flow - the exchange the call was for, or null

steps - the interpreter steps the call ran

allocBytes - about how many bytes of values the call created (an estimate)

nanos - how long the call took

budgetExceeded - the budget the call ran out of, "steps", "memory" or "time", or null

error - why the call failed, or null when it returned