xray_serverpod_interceptor 0.1.0

Shows the calls a Serverpod client makes in the xRay network inspector, by endpoint and method, with readable arguments, results and errors.

xray_serverpod_interceptor

Shows the calls your Flutter or Dart app makes to a Serverpod backend in the xRay network inspector: by endpoint and method (user.getProfile), with the arguments and results as formatted JSON, server exceptions with their type and fields, and whether the call was made signed in.

For full documentation and guides, visit xrayinspector.dev.

---

Disclaimer: This is a commercial package. To use this package, you need to have either a commercial xRay license or a free xRay Community License. The xRay macOS, iOS, and Android apps are the authorized UI clients for this library. For more details, please check the LICENSE file.

Requirements

serverpod_client 4.0.0 or newer: the package plugs into the client's httpClientOverride.

Setup

Pass an XRayServerpodHttpClient to your generated client:

final networkInspector = XRayNetworkInspector();

final client = Client(
  'https://api.example.com/',
  httpClientOverride: XRayServerpodHttpClient(inspector: networkInspector),
)..authSessionManager = FlutterAuthSessionManager();

Register networkInspector with your XRayInspectorServer as usual.

• Your own HTTP client. To keep a platform client such as CupertinoClient or CronetClient, pass it as inner: XRayServerpodHttpClient(inspector: networkInspector, inner: CupertinoClient.defaultSessionConfiguration()). httpClientOverride cannot be combined with Serverpod's securityContext; configure the context on the inner client instead.
• Timeouts. Serverpod applies its connectionTimeout outside the HTTP client, so xRay marks a call as timed out after its own connectionTimeout. It defaults to 20 seconds, like Serverpod's; if you changed the client's timeout, pass the same value.

What you see

• Title: endpoint.method. Module endpoints include the module name as the server knows it, e.g. serverpod_auth_core.status.isSignedIn.
• Arguments and results as formatted JSON. Binary values (ByteData) are shown as <binary, N bytes>, and bodies over 1 MB are cut off.
• Server exceptions (SerializableException) mark the call as failed with the exception's class name; the response body shows its fields. Other non-200 responses fail as HTTP <status>.
• Network failures (no connection, timeout) mark the call as failed with the reason.
• Signed in: whether the call carried the user's auth key, and the user id for JWT sessions (serverpod_auth_core). Server-side sessions and legacy serverpod_auth keys carry no user id.
• Auth key masked: the authorization header is recorded as the scheme plus at most the last 4 characters of the key (Bearer …a1b2), like the other credential headers the network inspector masks by default. The user id above is read before masking. Use redactHeaders on the XRayNetworkInspector to change this; see Masking credentials in the xray_inspector README.
• Server: the host each call went to, so several clients in one app can be told apart.

File uploads

Serverpod's FileUploader does not use httpClientOverride. Use XRayServerpodFileUploader instead; it has the same API and calls FileUploader for you:

final description = await client.files.getUploadDescription('avatar.png');
final uploader = XRayServerpodFileUploader(description!, inspector: networkInspector);
final success = await uploader.uploadByteData(bytes);

The upload shows up as Upload avatar.png with its size, destination, duration and whether it succeeded.

Not captured yet

Streaming methods and streams run over a WebSocket that Serverpod opens without any hook for other packages, so they do not show up. This needs a client interceptor in Serverpod (serverpod/serverpod#5141); the package will switch to it once it ships.

Using it together with enableHttpOverride

The client tells the global HttpClient override to skip the requests it already records, so every Serverpod call shows up once. Requests are matched on method and URL; no header or other marker is added to the request.