Forem: Silfalion

Tip: add default headers to Serverpod endpoint calls today with a custom client

Silfalion — Tue, 28 Apr 2026 14:46:41 +0000

Serverpod does not currently expose a public defaultHeaders or headersProvider option for generated endpoint
HTTP calls.

That can be awkward for values like Accept-Language, tenant IDs, app-version metadata, or other request-scoped
headers you want on many endpoint calls without threading an extra argument through every endpoint method.

You can work around this today by subclassing the generated client and overriding callServerEndpoint.

Client workaround

import 'package:http/http.dart' as http;
import 'package:serverpod_client/serverpod_client.dart';

import 'src/protocol/client.dart';

class AppClient extends Client {
  AppClient(super.host, {super.securityContext});

  final _http = http.Client();

  final Map<String, String> defaultHeaders = {};

  @override
  Future<T> callServerEndpoint<T>(
    String endpoint,
    String method,
    Map<String, dynamic> args, {
    bool authenticated = true,
  }) async {
    final auth = authenticated ? await authKeyProvider?.authHeaderValue : null;

    final response = await _http
        .post(
          Uri.parse('$host$endpoint'),
          headers: {
            'content-type': 'application/json; charset=utf-8',
            if (auth != null) 'authorization': auth,
            ...defaultHeaders,
          },
          body: SerializationManager.encode({
            ...args,
            'method': method,
          }),
        )
        .timeout(connectionTimeout);

    if (response.statusCode != 200) {
      throw ServerpodClientException(response.body, response.statusCode);
    }

    if (T == getType<void>()) return null as T;
    return serializationManager.decode<T>(response.body, T);
  }

  @override
  void close() {
    _http.close();
    super.close();
  }
}

Global usage

final client = AppClient('http://localhost:8080/')
  ..defaultHeaders['accept-language'] = 'fr-FR';

Now normal generated endpoint calls made through that client include the header:

await client.greeting.hello('Ada');

Grouped usage

If only one feature area needs the extra headers, prefer a preconfigured client for that feature instead of
mutating one shared client back and forth.

class LocalizedGreetingApi {
  LocalizedGreetingApi(Client baseClient)
      : client = AppClient(baseClient.host)
          ..authKeyProvider = baseClient.authKeyProvider
          ..defaultHeaders['accept-language'] = 'fr-FR';

  final AppClient client;

  Future<String> hello(String name) {
    return client.greeting.hello(name);
  }
}

Server-side read

Future<String> hello(Session session, String name) async {
  final language = session.request?.headers['accept-language']?.firstOrNull;
  return 'hello $name ($language)';
}

Important production note

This workaround extends the generated Serverpod client, but it does not hook into a smaller official “add headers
here” API. Serverpod’s lower-level endpoint implementation is private, and the internal request delegate currently
does not accept custom headers.

That means overriding callServerEndpoint takes ownership of the normal endpoint HTTP request path.

For simple cases, the snippet above is enough. For production apps that use RefresherClientAuthKeyProvider, JWT
refresh, onFailedCall, or onSucceededCall, you may want to preserve a little more of Serverpod’s built-in
behavior.

The main behavior to preserve is:

call onSucceededCall after successful endpoint calls
call onFailedCall when calls fail
map common HTTP status codes to Serverpod exceptions
on 401, refresh the auth key once and retry

Here is a more complete version:


import 'package:http/http.dart' as http;
import 'package:serverpod_client/serverpod_client.dart';

import 'src/protocol/client.dart';

class AppClient extends Client {
  AppClient(
    super.host, {
    super.securityContext,
    super.authenticationKeyManager,
    super.streamingConnectionTimeout,
    super.connectionTimeout,
    super.onFailedCall,
    super.onSucceededCall,
    super.disconnectStreamsOnLostInternetConnection,
  });

  final _http = http.Client();

  final Map<String, String> defaultHeaders = {};

  @override
  Future<T> callServerEndpoint<T>(
    String endpoint,
    String method,
    Map<String, dynamic> args, {
    bool authenticated = true,
  }) async {
    try {
      return await _callServerEndpointWithDefaultHeaders<T>(
        endpoint,
        method,
        args,
        authenticated: authenticated,
      );
    } on ServerpodClientUnauthorized {
      final keyProvider = authKeyProvider;

      if (keyProvider is RefresherClientAuthKeyProvider) {
        final refreshResult = await keyProvider.refreshAuthKey(force: true);

        if (refreshResult == RefreshAuthKeyResult.success) {
          return _callServerEndpointWithDefaultHeaders<T>(
            endpoint,
            method,
            args,
            authenticated: authenticated,
          );
        }
      }

      rethrow;
    }
  }

  Future<T> _callServerEndpointWithDefaultHeaders<T>(
    String endpoint,
    String method,
    Map<String, dynamic> args, {
    required bool authenticated,
  }) async {
    final callContext = MethodCallContext(
      endpointName: endpoint,
      methodName: method,
      arguments: args,
    );

    try {
      final auth = authenticated ? await authKeyProvider?.authHeaderValue : null;

      final response = await _http
          .post(
            Uri.parse('$host$endpoint'),
            headers: {
              'content-type': 'application/json; charset=utf-8',
              if (auth != null) 'authorization': auth,
              ...defaultHeaders,
            },
            body: SerializationManager.encode({
              ...args,
              'method': method,
            }),
          )
          .timeout(connectionTimeout);

      if (response.statusCode != 200) {
        throw _exceptionFromResponse(response);
      }

      final result = T == getType<void>()
          ? null as T
          : serializationManager.decode<T>(response.body, T);

      onSucceededCall?.call(callContext);
      return result;
    } catch (error, stackTrace) {
      onFailedCall?.call(callContext, error, stackTrace);
      rethrow;
    }
  }

  ServerpodClientException _exceptionFromResponse(http.Response response) {
    switch (response.statusCode) {
      case 400:
        return ServerpodClientBadRequest(response.body);
      case 401:
        return ServerpodClientUnauthorized();
      case 403:
        return ServerpodClientForbidden();
      case 404:
        return ServerpodClientNotFound();
      case 500:
        return ServerpodClientInternalServerError();
      default:
        return ServerpodClientException(response.body, response.statusCode);
    }
  }

  @override
  void close() {
    _http.close();
    super.close();
  }
}

Caveats

This is for normal generated endpoint HTTP calls only.
This is not for method streams.
Do not use this to override authorization.
Do not use this to override content-type.
If you need arbitrary custom headers from browser clients, remember CORS can matter.
If your app relies on JWT refresh, use the production-aware version above or add equivalent 401 retry behavior.
This is a workaround until Serverpod exposes first-class default headers or a headers provider on the client.

Why not just extend a lower-level client hook?

A smaller hook would be the cleanest version of this.

At the moment, the public extension point for generated endpoint calls is callServerEndpoint. The lower-level
request implementation is kept private, which makes sense: Serverpod owns serialization, request formatting,
exception mapping, auth retry, and IO/browser differences there. Keeping that internal gives the framework room to
evolve without locking users into those details.

What would make this use case nicer is a focused public hook that only customizes headers, without exposing the
rest of the request pipeline. For example:

final client = Client(
  'http://localhost:8080/',
  headersProvider: () async => {
    'accept-language': currentLocale,
  },
);

or:

client.defaultHeaders['accept-language'] = 'fr-FR';

Until Serverpod adds an API along those lines, overriding callServerEndpoint is a pragmatic workaround. It keeps
the generated endpoint API intact, while making the tradeoff explicit: you are taking over the HTTP request path
for normal endpoint calls.

Debug and deploy your flutter app with an iPhone on Linux

Silfalion — Thu, 14 Oct 2021 11:21:56 +0000

Freedom, what a liberating feeling, it may take a few years, a centery or just a few steps to attain it. It's the feeling I've been yearning off as an aspiring ios developper for many many years, and thanks to many increadible people, I finally attained it and hope you will as well 😌.

Enough bla bla. What we're gonna go through in this post is how to debug your flutter app, and non-flutter ios ones if you want, with your iphone on linux.

Concept

This approach essentially consists in installing a VM with macos and XCode, passthrough your usb controller to be able to use your iphone and then ssh into. If you know how to do all this already look a little more at the bottom as there a few setup to do in order to make you able to debug any app.

Ok, it has some caveats

First of all this will require approximatively 70 Gb, yes 70, at first at least. This is because we're installing macos in its entirety plus XCode, so storage is the first inconvenience of this approach. This can become overcome in a certain measure through a certain number of tricks and tips.
DISCLAIMER: you won't be downloading 70 Gb, just 30~ :3

Second caveats is that since we're running a VM, this is very processor and battery intensive, so basically using this approach on the move on a laptop wouldn't be very efficient.

Basically if you have enough storage and have a power plug near you or are on desktop this approach should be a delight ✨.

The incredible people mentioned prior:

Miko
Reinis
Sick.codes, the author of docker-osx multi-talent automator.
Dortania stuff
Kholia

iPhone passthrough

This step is already very detailed in my repo. It consists of:

Downloading the OSX VM.
Making your usb controller available to the VM.
Adding the necessary instructions to the docker container launch script.
launching the VM and that's all.

Setting up our environement for flutter

Now that you can detect your iDevice on macos, we can now fetch somehow our Flutter/Swift project, and for that we have multiple options:

If your project is on Github you can clone it into your macos VM through the command line(ssh below) or the GUI. Then you commit, push/pull on macos or vice versa to sync changes.
secure copy into the VM, like so:

scp -P 50922 -r /folder/you/want/to/transfer username_VM@localhost:/folder/you/to/put/it/in

The third option would be to share the project from your host to your guest and that theoritically allow any changes made to one to reflect on the other. I unfortunately couldn't get this to work at the time of writing this article.

The sharing works and the folder appears on both systems but the problem that kept occuring was that the shared folder wasn't given enough permissions from the host. I'm sure this can be easily fixed with more research but couldn't allocate it more time.

SSHIng into the VM

One of the most powerful aspects of this trick is that you can even run a remote MacOS VM and be able to develop almost as if it's your system. This is possible through SSH.

We'll basically SSH into our VM through VsCode. We'll first activate this option in the VM by activating remote login:

Go into settings.
Select remote control.
Check remote login, enter password if asked.
Done!

The second step is setting the link(ports) on the host, very simple allowed thanks to Sick.codes by adding this line in the docker script we use to launch the VM:

    -p 50922:10022 \

Now we can connect through vscode:

Open vscode and type CTRL+SHIFT+P
Type ssh and select "Remote-SSH: Add New SSH Host"
Make sure the VM is connected and press enter, enter your macos password then press enter again. DISCLAIMER this may be different if you have a remote VM set or changed the VM password previously.
Vscode will now open a new window that will be connected to your VM.
Navigate to or create your flutter project whereever you like. Just like you'd do on your host, but all through vscode.

You should now have your project in front of you and your iPhone recognized as a device, you can check that by running:

flutter devices

in the vscode terminal.

I noticed that there are some issues if the right permissions are not given to the project, so I just give it all permissions through

chmod -R 777

. I'm not working with security sensitive data at the moment but in most cases you should revaluate the permissions you give and be careful about it.

Setting up xcode

XCode needs your account so that it can sign your apps and deploy them to your device.

To do that go to xcode on your VM and open the file called .workspce under ios/runner in your flutter project. Select runner in the file tree on the left then singing and capabilities in the bar in the middle top of the screen. Choose your team or create one by connecting your apple id then hit sign in. This is necessary to generate the certificates for your apps and would be needed even for a normal mac setup.

Finale

Now go back to your vm connected vscode window on your host and run this last line:

security unlock-sign in

This is necessary because otherwise macos will bother you by opening a prompt to enter your password. Look more into if you need to increase your security.

You should now be able to compile and deploy your project to your iPhone.

Bonus

To economize some CPU and GPU power, you can launch your VM without a display output, so just delete this line from the script:

-e "DISPLAY=${DISPLAY:-:0.0}" \

Help

This is quite a mixed up mess of possibly poorly written information so if you need clarification with anything or improvements, direct your issues here please:

https://github.com/Silfalion/Iphone_docker_osx_passthrough

Just make sure you've read the article thoroughly before positng.

Happy coding 😄!