website refactor
This commit is contained in:
272
docs/architecture/website/SESSION.md
Normal file
272
docs/architecture/website/SESSION.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Next.js RSC Session Best Practices
|
||||
|
||||
This document defines the authoritative pattern for handling session/authentication in Next.js Server Components and Server Actions within the `apps/website` layer.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Server Actions should NOT fetch session separately.** The API handles authentication automatically via cookies.
|
||||
|
||||
## The Problem with Manual Session Fetching
|
||||
|
||||
### ❌ Anti-Pattern (Current Implementation)
|
||||
```typescript
|
||||
// apps/website/app/onboarding/actions.ts
|
||||
'use server';
|
||||
|
||||
import { SessionGateway } from '@/lib/gateways/SessionGateway';
|
||||
|
||||
async function getCurrentUserId(): Promise<string | null> {
|
||||
const gateway = new SessionGateway();
|
||||
const session = await gateway.getSession(); // ❌ Extra API call
|
||||
return session?.user?.userId || null;
|
||||
}
|
||||
|
||||
export async function completeOnboardingAction(input: CompleteOnboardingInputDTO) {
|
||||
const userId = await getCurrentUserId(); // ❌ Performance overhead
|
||||
if (!userId) {
|
||||
return Result.err('Not authenticated');
|
||||
}
|
||||
|
||||
const mutation = new CompleteOnboardingMutation();
|
||||
// ... rest of logic
|
||||
}
|
||||
```
|
||||
|
||||
**Problems:**
|
||||
1. **Performance**: Makes extra API call on every action invocation
|
||||
2. **Redundancy**: Manual auth check when API handles it automatically
|
||||
3. **Coupling**: Actions depend on session infrastructure
|
||||
4. **Inconsistency**: Doesn't match pattern used elsewhere in codebase
|
||||
|
||||
## The Correct Pattern
|
||||
|
||||
### ✅ Server Actions (Thin Wrappers)
|
||||
```typescript
|
||||
// apps/website/app/onboarding/actions.ts
|
||||
'use server';
|
||||
|
||||
import { Result } from '@/lib/contracts/Result';
|
||||
import { CompleteOnboardingMutation } from '@/lib/mutations/onboarding/CompleteOnboardingMutation';
|
||||
import { GenerateAvatarsMutation } from '@/lib/mutations/onboarding/GenerateAvatarsMutation';
|
||||
import { CompleteOnboardingInputDTO } from '@/lib/types/generated/CompleteOnboardingInputDTO';
|
||||
import { revalidatePath } from 'next/cache';
|
||||
|
||||
/**
|
||||
* Complete onboarding - thin wrapper around mutation
|
||||
*
|
||||
* Pattern: Server Action → Mutation → Service → API Client
|
||||
*
|
||||
* Authentication is handled automatically by the API via cookies.
|
||||
* The BaseApiClient includes credentials: 'include', so cookies are sent automatically.
|
||||
* If authentication fails, the API returns 401/403 which gets converted to domain errors.
|
||||
*/
|
||||
export async function completeOnboardingAction(
|
||||
input: CompleteOnboardingInputDTO
|
||||
): Promise<Result<{ success: boolean }, string>> {
|
||||
const mutation = new CompleteOnboardingMutation();
|
||||
const result = await mutation.execute(input);
|
||||
|
||||
if (result.isErr()) {
|
||||
return Result.err(result.getError());
|
||||
}
|
||||
|
||||
revalidatePath('/dashboard');
|
||||
return Result.ok({ success: true });
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate avatars - thin wrapper around mutation
|
||||
*
|
||||
* Note: This action requires userId to be passed from the client.
|
||||
* The client should get userId from session and pass it as a parameter.
|
||||
*/
|
||||
export async function generateAvatarsAction(params: {
|
||||
userId: string;
|
||||
facePhotoData: string;
|
||||
suitColor: string;
|
||||
}): Promise<Result<{ success: boolean; avatarUrls?: string[] }, string>> {
|
||||
const mutation = new GenerateAvatarsMutation();
|
||||
const result = await mutation.execute(params);
|
||||
|
||||
if (result.isErr()) {
|
||||
return Result.err(result.getError());
|
||||
}
|
||||
|
||||
const data = result.unwrap();
|
||||
return Result.ok({ success: data.success, avatarUrls: data.avatarUrls });
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ Client Component Pattern
|
||||
```typescript
|
||||
// apps/website/app/onboarding/OnboardingWizardClient.tsx
|
||||
'use client';
|
||||
|
||||
import { completeOnboardingAction, generateAvatarsAction } from '@/app/onboarding/actions';
|
||||
import { useAuth } from '@/lib/hooks/auth/useAuth';
|
||||
import { useState } from 'react';
|
||||
|
||||
export function OnboardingWizardClient() {
|
||||
const { session } = useAuth(); // Get userId from session (client-side)
|
||||
const [isSubmitting, setIsSubmitting] = useState(false);
|
||||
|
||||
const handleCompleteOnboarding = async (input: CompleteOnboardingInputDTO) => {
|
||||
setIsSubmitting(true);
|
||||
try {
|
||||
const result = await completeOnboardingAction(input);
|
||||
|
||||
if (result.isErr()) {
|
||||
// Handle error (show toast, etc.)
|
||||
console.error('Onboarding failed:', result.getError());
|
||||
return;
|
||||
}
|
||||
|
||||
// Success - redirect or show success message
|
||||
console.log('Onboarding completed successfully');
|
||||
} finally {
|
||||
setIsSubmitting(false);
|
||||
}
|
||||
};
|
||||
|
||||
const handleGenerateAvatars = async (facePhotoData: string, suitColor: string) => {
|
||||
if (!session?.user?.userId) {
|
||||
console.error('User not authenticated');
|
||||
return Result.err('Not authenticated');
|
||||
}
|
||||
|
||||
setIsSubmitting(true);
|
||||
try {
|
||||
const result = await generateAvatarsAction({
|
||||
userId: session.user.userId, // Pass userId from session
|
||||
facePhotoData,
|
||||
suitColor,
|
||||
});
|
||||
|
||||
if (result.isErr()) {
|
||||
console.error('Avatar generation failed:', result.getError());
|
||||
return;
|
||||
}
|
||||
|
||||
const data = result.unwrap();
|
||||
console.log('Avatars generated:', data.avatarUrls);
|
||||
} finally {
|
||||
setIsSubmitting(false);
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<div>
|
||||
{/* Wizard implementation */}
|
||||
<button onClick={() => handleCompleteOnboarding({ firstName: 'John', lastName: 'Doe', displayName: 'JohnD', country: 'US' })}>
|
||||
Complete Onboarding
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Why This Pattern Works
|
||||
|
||||
### 1. Automatic Authentication
|
||||
```typescript
|
||||
// apps/website/lib/api/base/BaseApiClient.ts
|
||||
protected async request<T>(method: string, path: string, data?: object, options = {}): Promise<T> {
|
||||
const config: RequestInit = {
|
||||
method,
|
||||
headers,
|
||||
credentials: 'include', // ✅ Automatically sends cookies
|
||||
signal,
|
||||
};
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
The `BaseApiClient` automatically includes `credentials: 'include'`, so:
|
||||
- Cookies are sent with every API request
|
||||
- The backend API can authenticate the user
|
||||
- No manual session fetching needed in server actions
|
||||
|
||||
### 2. Error Handling Flow
|
||||
```
|
||||
User not authenticated
|
||||
↓
|
||||
API returns 401/403
|
||||
↓
|
||||
BaseApiClient throws HttpUnauthorizedError
|
||||
↓
|
||||
Service catches and converts to DomainError
|
||||
↓
|
||||
Mutation returns Result.err()
|
||||
↓
|
||||
Server Action returns error to client
|
||||
↓
|
||||
Client shows appropriate message
|
||||
```
|
||||
|
||||
### 3. Performance Benefits
|
||||
- **No extra API calls**: Session fetched once on client, reused
|
||||
- **Reduced latency**: Server actions don't wait for session lookup
|
||||
- **Better scalability**: Fewer API calls per user action
|
||||
|
||||
### 4. Consistency with Architecture
|
||||
This pattern matches your existing codebase:
|
||||
```typescript
|
||||
// apps/website/app/admin/actions.ts - ✅ Already follows this pattern
|
||||
export async function updateUserStatus(userId: string, status: string) {
|
||||
const mutation = new UpdateUserStatusMutation();
|
||||
const result = await mutation.execute({ userId, status });
|
||||
// ... no manual session fetching
|
||||
}
|
||||
```
|
||||
|
||||
## When Manual Session Fetching IS Needed
|
||||
|
||||
There are rare cases where you might need to fetch session in a server action:
|
||||
|
||||
### Case 1: User ID Required in Request Body
|
||||
If the API endpoint requires userId in the request body (not just cookies):
|
||||
|
||||
```typescript
|
||||
// Client passes userId
|
||||
const result = await generateAvatarsAction({
|
||||
userId: session.user.userId, // ✅ Pass from client
|
||||
facePhotoData,
|
||||
suitColor,
|
||||
});
|
||||
```
|
||||
|
||||
### Case 2: Server-Side Authorization Check
|
||||
If you need to check permissions before calling a mutation:
|
||||
|
||||
```typescript
|
||||
export async function adminAction(input: AdminInput) {
|
||||
// Only fetch session if you need to check permissions server-side
|
||||
const gateway = new SessionGateway();
|
||||
const session = await gateway.getSession();
|
||||
|
||||
if (!session?.user?.roles?.includes('admin')) {
|
||||
return Result.err('Forbidden');
|
||||
}
|
||||
|
||||
const mutation = new AdminMutation();
|
||||
return await mutation.execute(input);
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: This is rare. Usually, the API handles authorization and returns 403 if unauthorized.
|
||||
|
||||
## Summary
|
||||
|
||||
| Aspect | Manual Session Fetching | Automatic (Recommended) |
|
||||
|--------|------------------------|------------------------|
|
||||
| **Performance** | ❌ Extra API call | ✅ No overhead |
|
||||
| **Complexity** | ❌ More code | ✅ Simpler |
|
||||
| **Coupling** | ❌ Depends on session infra | ✅ Decoupled |
|
||||
| **Consistency** | ❌ Inconsistent | ✅ Matches codebase |
|
||||
| **Security** | ⚠️ Manual checks | ✅ API enforces |
|
||||
|
||||
## Golden Rule
|
||||
|
||||
**Server Actions are thin wrappers. Mutations handle logic. API enforces security.**
|
||||
|
||||
Never fetch session in server actions unless you have a specific server-side authorization requirement that cannot be handled by the API.
|
||||
Reference in New Issue
Block a user