Allow setting the fetch implementation in the sdk

[fehnomenal]

Summary

I want to specify a custom fetch implementation, when calling .with(auth()), .with(rest()) or .with(graphql()). Basically everything which ultimately calls the request utility function.

Basic Example

import fetch from 'cross-fetch';

createDirectus('http://localhost:8055').with(rest({ fetch });

or sveltekit specific:

export const load = (event) => {
  const directus = createDirectus('http://localhost:8055').with(rest({ fetch: event.fetch });
};

Motivation

My main motivation is using the sdk with server-side rendering in sveltekit but I guess it will also be beneficial for environments without global fetch like old node versions.

Sveltekit gives us a wrapped fetch function. During SSR responses from calls of the wrapper are inlined in the html and can be replayed on the client without doing the request again.

Detailed Design

The composables auth and rest already accept optional config arguments. graphql will be expanded to also accept an optional argument GraphqlConfig.
All of these types extend:

interface RequestConfig {
  fetch?: typeof globalThis.fetch;
}

By creating a dedicated config interface for each composable there is the infrastructure for more config options in the future.

The request utility will take a config?: RequestConfig and use the fetch if provided and else the global fetch:

-const response = await globalThis
-	.fetch(url, options)
+const response = await (config?.fetch ?? globalThis.fetch)(url, options)

Each composable calls request with the new config argument.

Requirements List

Must Have:

• ability to pass custom fetch implementation

Drawbacks

• Implementation effort seems rather low
• not possible to implement in user land (except for copying large parts of the code)
• teaching will be easy in the docs
• all planned composables would need to take this into account
• not breaking because of the optional config and fallback

Alternatives

Allowing to replace the whole request utility. This would be more or less the same config wise (or each extension would need a reference to the client class which could hold the custom request function).
Seems more flexible but also more verbose for the developers.

Adoption Strategy

not needed as this is non-breaking

Unresolved Questions

No response

[fehnomenal]

I will begin working on this even if not accepted as I need it for my project. If not accepted I will use this with patch-package or something similar.

[br41nslug]

I did consider this at some point but opted not to implement that because it is already possible using the globalThis object. Any specific reason you dont want to use the globalThis.fetch function in such a manner within svelte? 🤔

or sveltekit specific:

export const load = (event) => {
  globalThis.fetch = event.fetch;
  const directus = createDirectus('http://localhost:8055').with(rest());
};

Or even like so when wanting to preserve the original fetch (which i dont think is technically needed within this SSR context if it's properly isolated per request, but i could be missing something ofc):

export const load = (event) => {
  const origFetch = globalThis.fetch;
  globalThis.fetch = event.fetch;
  const directus = createDirectus('http://localhost:8055').with(rest();
  globalThis.fetch = origFetch;
};

This would be the way to polyfill (or overwrite) any of the APIs used by the SDK that are either missing in the JS runtime or just need to be overwritten for reasons.

[fehnomenal]

I thought the same at first but I don't really feel safe to overwrite a shared global on the server which is used to make (potentially) authenticated calls and whose result is returned in HTML. Maybe the single threaded nature of node makes this not a problem but I feel a bit uneasy about that.

Apart from that, I would like to create a directus client scoped to the current request. In sveltekit this is done with event.locals. Otherwise I would need to include this boilerplate (well, one statement) before each call to .request() as another incoming request could have overwritten the current fetch with their own while the current function was waiting for the promise to resolve. A diagram to visualize:

sequenceDiagram
    participant req1 as SvelteKit Request 1
    participant req2 as SvelteKit Request 2
    participant api as Directus API

    note over req1: begin handling request
    activate req1
    req1-->>req1: globalThis.fetch = event.fetch
    req1->>+api: first call (1.1)

    note over req2: begin handling request
    activate req2
    req2-->>req2: globalThis.fetch = event.fetch
    req2->>+api: call (2)

    api-->>-req2: response
    api-->>-req1: response

    req1->>+api: second call (1.2 with wrong globalThis.fetch)
    api-->>-req1: response
    deactivate req1
    note over req1: end handling request

    req2-->req2: unrelated stuff that takes time
    deactivate req2
    note over req2: end handling request

This would mean:

1. The SSR response for request 1 would not include the response (1.2) of the second directus call, which is unfortunate but not the end of the world as the browser would simply do the request again.
2. But worse: if the handling of request 2 finishes after the second directus call (1.2) from request 1 the SSR response would include the response (1.2) which might include data the user of request 2 has no permissions to.

[Sandros94]

I thought the same at first but I don't really feel safe to overwrite a shared global on the server which is used to make (potentially) authenticated calls and whose result is returned in HTML. Maybe the single threaded nature of node makes this not a problem but I feel a bit uneasy about that.

If I'm not mistaken this could be greater problem when node-workers come in to play. But I still have a limited understanding on this topic.

[Sandros94]

I would like to give my opinion on this, but I would also like to bring a bigger picture on the topic.

I wouldn't focus on a per-framework basis, but on something that most of them do already (and usually highly optimize on their own). The good old fetch.

What I see as the problem

Currently the SDK forces the use of plain fetch. While this is a great starting point, that gets people to a working state, it can easily become a nightmare when we consider environment specific rendering modes (servers/serverless that would make possible: SPA, SSG, SSR and so on).

This is because, for sake of optimization and improvements, each framework could bring its own custom-fetch with usually a common task: be sure to run well on each of the environment that the framework supports, like NodeJS, Vercel, Netlify, Heroku, AWS, Azure, Cloudflare, $4-YourNameHere (just kidding).

And this is the point: why force the framework where the SDK is being used at to use a fetch that could potentially create problems at runtime? I can already see hundreds of issues opened in the related frameworks or ${FRAMWORK_NAME}-directus module's repo.

I love the idea of having a default fetch, like it is currently, but I could already see a greater number of people enjoying the ability to use their custom fetch if needed, taking advantage of optimizations that the devs behind that particular framework already have done, or even better actively maintain.

The solutions I see

• Provide a config?.fetch: much like @fehnomenal suggested give the devs the ability to overwrite what fetch to use when calling createDirectus:

  import { ofetch } from 'ofetch';
  createDirectus('http://localhost:8055').with(rest({ ofetch });

  This, in my opinion, would be the optimal solution that I could think of as of now. With the best DX and maintainability.
• Replace the request utility: again, as @fehnomenal already suggested, this would be a sub-optimal, but still great, solution. The biggest drawbacks I could see coming are:
  • a more complex task to do and maintain.
  • in the event of a major release/rework of the SDK I could easily see this being a breaking change.
• Forking/Rewriting the SDK into something separate: This is the solution I would like never take place. Because I see it like us (OSS enjoyers) fighting each other, wasting countless of valuable hours.

Who would benefit from this?

Ofc Directus-SDK popularity and usage on the main frameworks, but mainly each directus-module/plugin maintainers for their respective framework. This would not only make the SDK the main source of truth (good practices in Directus usage), but most importantly take advantage of the framework-specific tools, even other than fetch!

Take in consideration framework-specific tools (that potentially are implemented differently one from the other) like Payload Caching (huge for preventing multiple API requests), State Managements, Rendering Modes and so on. Making the creation of custom composable built on-top of the SDK incredibly easy, that could potentially never be created just because devs couldn't use their custom-fetch optimizing their framework in use (aka the starting point).

Personal notes

I've come to realize this issue when discussing the rewrite of the nuxt-directus module with @Intevel, @casualmatt and @rijkvanzanten.
But, as easy (by the great SDK you guys created) the task has seemed, I soon realized that with current state of the SDK, while great for general js use, it might not be suitable for most frameworks (at least on a higher level of integration). Making the consideration of a full rewrite without the SDK even an option!!

[rijkvanzanten]

This feature request has been accepted and is queued to be implemented! You can follow along with the progress here: #19592

[br41nslug]

This feature request was implemented here #19606 merged and shipped 😄

[panos-stavrianos]

Hello, has anyone managed to make it work with sveltekit?

export async function load(event) {

    const client = createDirectus('https://mydirectus', {
        globals: {
            fetch: event.fetch,
        }
    }).with(rest())

    const result = await client.request(readSingleton('site_info'));
    ...
}

I get the following error

errors: Error: Failed to get response header "content-type" — it must be included by the `filterSerializedResponseHeaders` option

[br41nslug]

During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the text and json methods of the Response object. Note that headers will not be serialized, unless explicitly included via filterSerializedResponseHeaders.

Tend to use svelte without the kit myself usually but a quick search through the docs says you'll need to use the mentioned function to set a content-type headers when working on the server-side

https://kit.svelte.dev/docs/load#making-fetch-requests

[panos-stavrianos]

Thanks for the quick response, i guess i missed that in the docs.
For anyone getting the same error, i did that

// src/hooks.server.js
export async function handle({event, resolve}) {

    return await resolve(event, {
        filterSerializedResponseHeaders: (key, value) => {
            return key === 'content-type'
        }
    });
}

Feel free to correct me if there is a better way, i am pretty new in sveltekit