fix: prevent race condition in async token refresh

[mandarini]

What kind of change does this PR introduce?

Automatically initialize session on server client creation to trigger token refresh early in request lifecycle. This prevents race condition where refresh completes after response is sent, causing cookie errors. Also adds helpful error context before throwing if edge cases occur.

What is the current behavior?

Error: Cannot use `cookies.set(...)` after the response has been generated

Most possibly caused by token refresh.

What is the new behavior?

Initialize session to trigger token refresh early.

[hf]

I'm a bit scared of this as it runs all the time when the server gets created, but without the ability to set cookies if that's needed

[mandarini]

@hf Yeah I agree, it's a slippery slope. I wonder if there's a better way to treat this, and not get that race condition issue.

[ixxie]

@mandarini thanks for opening this, I'm running into this issue since I had to upgrade from Vite 5 => 7 in a SvelteKit project.

Important

Svelte and SvelteKit are moving really fast right now, since they have experimental support for async Svelte and SvelteKit remote functions. So SvelteKit users that want to keep dependencies up to day have to bump Vite to 7.

Is there a workaround I could do to the recommended approach from the docs to sidestep the issue? The best I could come up with (with Claude's help) is:

export const handle: Handle = async ({ event, resolve }) => {
  // Creates a Supabase client specific to this server request.
  // The Supabase client gets the Auth token from the request cookies.
  event.locals.supabase = createServerClient(
    PUBLIC_SUPABASE_URL,
    PUBLIC_SUPABASE_ANON_KEY,
    {
      cookies: {
        getAll: () => event.cookies.getAll(),
        // SvelteKit requires cookie `path` to be explicity set
        setAll: (cookiesToSet) => {
          cookiesToSet.forEach(({ name, value, options }) => {
            event.cookies.set(name, value, { ...options, path: '/' });
          });
        },
      },
    },
  );

  // Workaround for supabase/ssr#131: trigger token refresh early
  // before resolve() to prevent race condition with Vite 7
  await event.locals.supabase.auth.getSession();

  // Unlike `supabase.auth.getSession()`, which returns the session _without_
  // validating the JWT, this function also calls `getUser()` to validate the
  // JWT before returning the session.
  event.locals.safeGetSession = async () => {
    const {
      data: { session },
    } = await event.locals.supabase.auth.getSession();
    // no session
    if (!session) {
      return { session: null, user: null };
    }

    const {
      data: { user },
      error,
    } = await event.locals.supabase.auth.getUser();
    // no jwt token
    if (error) {
      return { session: null, user: null };
    }

    return { session, user };
  };

  return resolve(event, {
    filterSerializedResponseHeaders(name) {
      // forward supabase headers
      return name === 'content-range' || name === 'x-supabase-api-version';
    },
  });
};

[mandarini]

Summoning @hf, maybe some better solution for @ixxie ?