Integracja tRPC z React Query i uwierzytelnianiem

Kontekst tRPC to obiekt tworzony od nowa dla każdego żądania przez funkcję createTRPCContext. Może zawierać klienta bazy danych, uwierzytelnioną sesję, nagłówki żądania lub dowolne dane specyficzne dla danego żądania, których potrzebują procedury.

Tworzenie kontekstu odbywa się przed uruchomieniem dowolnej procedury, dlatego jest to właściwe miejsce na konfigurację uwierzytelniania i połączenia z bazą danych.

W createTRPCContext należy wywołać getServerSession(authOptions) z next-auth/next. Wynik należy dołączyć do obiektu kontekstu: return { session: await getServerSession(authOptions), db }. Wszystkie procedury mają teraz dostęp do ctx.session.

Jeśli session ma wartość null, użytkownik nie jest uwierzytelniony. Procedury mogą to sprawdzić, aby warunkowo zwrócić dane lub zgłosić błąd.

Należy zdefiniować middleware sprawdzający ctx.session: const isAuthenticated = t.middleware(({ ctx, next }) => { if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' }); return next({ ctx: { session: ctx.session } }); }).

Wywołanie next() przekazuje zawężony kontekst (z sesją, która nie może mieć wartości null) do kolejnych middleware i procedury obsługi.

Należy połączyć middleware z publicProcedure: const protectedProcedure = publicProcedure.use(isAuthenticated). Od tej pory każdy handler zdefiniowany za pomocą protectedProcedure.query() lub protectedProcedure.mutation() automatycznie otrzymuje w ctx sesję, która nie może mieć wartości null.

TypeScript wnioskuje, że ctx.session nie ma wartości null wewnątrz chronionych procedur, ponieważ middleware zgłosiłby błąd przed przekazaniem sterowania do handlera.

W przypadku endpointów wymagających uwierzytelnienia należy zastąpić publicProcedure przez protectedProcedure: protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id)). TypeScript wie, że ctx.session nie ma tutaj wartości null, dlatego dostęp do ctx.session.user.id jest bezpieczny i nie wymaga sprawdzania wartości null.

Nieuwierzytelnione żądania automatycznie otrzymują odpowiedź 401 UNAUTHORIZED przed wykonaniem handlera.

Należy przekazać funkcję headers do httpBatchLink: links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]. Funkcja jest wykonywana przed każdą partią żądań.

Stosuje się to podczas uwierzytelniania tRPC z klienta React Native lub dowolnego klienta spoza Next.js, który samodzielnie zarządza tokenami uwierzytelniającymi.

W celu renderowania po stronie serwera za pomocą Pages Router w Next.js należy utworzyć pomocnika po stronie serwera: createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) }). W getServerSideProps należy użyć helpers.post.getAll.prefetch().

Należy zdehydratyzować wstępnie pobrany stan za pomocą dehydrate(queryClient) i przekazać go jako props. Po stronie klienta QueryClient nawodni się na podstawie tego stanu, dzięki czemu nie trzeba ponownie pobierać danych przy pierwszym ładowaniu.

Plik _app.tsx aplikacji Next.js należy opakować komponentem Hydrate z @tanstack/react-query. Do właściwości state należy przekazać pageProps.trpcState. Spowoduje to przywrócenie po stronie klienta wstępnie pobranej pamięci podręcznej zapytań na podstawie zserializowanego stanu serwera.

Dzięki tej konfiguracji użytkownicy od razu widzą w pełni wypełnione strony, bez wskaźników ładowania po stronie klienta podczas pierwszej nawigacji.

Należy zgłaszać TRPCError z odpowiednimi kodami zgodnymi ze znaczeniem HTTP: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), BAD_REQUEST (400), INTERNAL_SERVER_ERROR (500). Klient tRPC mapuje je na odpowiednie stany błędów w wyniku hooka.

Pole message może zawierać szczegóły przeznaczone dla użytkownika, ale w komunikatach błędów na środowisku produkcyjnym należy unikać ujawniania poufnych informacji serwera.

tRPC współpracuje z klientami React Native przy użyciu tego samego typu AppRouter. Należy zastąpić httpBatchLink przez httpLink (fetch w RN działa tak samo) i skonfigurować nagłówki uwierzytelniania. Adapter @trpc/react-query działa tak samo jak w konfiguracji internetowej.

Oznacza to, że monorepo może współdzielić jeden router tRPC między aplikacją internetową Next.js a aplikacją Expo React Native, zapewniając pełne bezpieczeństwo typów w obu aplikacjach.

Wzorzec middleware można rozszerzyć o dostęp oparty na rolach: należy sprawdzać ctx.session.user.role i zgłaszać TRPCError({ code: 'FORBIDDEN' }), jeśli rola jest niewystarczająca. Należy utworzyć adminProcedure = publicProcedure.use(isAdmin) dla endpointów dostępnych wyłącznie dla administratorów.

W przypadku złożonej autoryzacji należy łączyć wiele middleware: publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...).

Kontekst tRPC jest tworzony dla każdego żądania i przechowuje sesję, klienta bazy danych oraz inne dane dostępne w zakresie danego żądania. Procedury chronione tworzy się przez dołączenie middleware sprawdzającego sesję do publicProcedure za pomocą .use(). Renderowanie po stronie serwera korzysta z createServerSideHelpers do wstępnego pobierania danych oraz z Hydrate do przywracania pamięci podręcznej po stronie klienta.

Nagłówki uwierzytelniania dla klientów spoza Next.js przekazuje się za pomocą opcji headers w httpBatchLink.