D-7: Server Actions & Route Handlers ① — 요청을 받기 시작한다

 오늘의 여정

 1. 아무것도 안 바뀝니다     우리가 보낸 요청을 세어본다
 2. 함수가 주소가 됩니다      'use server' -- 자바스크립트 없이도 동작한다
 3. 팔로우를 보냅니다         useActionState -- 결과와 오류를 받는다
 4. 굳은 것을 갈아 끼웁니다   updateTag -- 지난 시간의 이름표를 부른다
 5. 얼마나 굵게 부를까        이름표 하나 차이로 남의 화면까지 바뀐다
 6. 화면이 아닌 응답          Route Handler -- 그리고 두 함수의 진짜 차이
 7. 404 를 되찾습니다         proxy -- 그리기 전에 끼어드는 자리
 8. 그 404 의 값             2ms 가 405ms 가 된다

// apps/web-next/app/components/LikeButton.tsx
'use client';

import { useState } from 'react';

export function LikeButton({ likeCount, liked }: { likeCount: number; liked: boolean }) {
  const [pressed, setPressed] = useState(liked);
  const [count, setCount] = useState(likeCount);

  function toggle() {
    setPressed(!pressed);
    setCount(pressed ? count - 1 : count + 1);
  }

  return (
    <button
      type="button"
      aria-pressed={pressed}
      onClick={toggle}
      className="mt-2 text-sm text-black/60"
    >
      {pressed ? '♥' : '♡'} 좋아요 {count}
    </button>
  );
}

API_STUB_LOG=1 node apps/api-stub/server.mjs

curl -s -o /dev/null http://localhost:3000/
curl -s -o /dev/null http://localhost:3000/explore
curl -s -o /dev/null http://localhost:3000/jaehoon
curl -s -o /dev/null http://localhost:3000/minji

 GET       9 건
 그 외      0 건

// apps/web-next/app/actions/session.ts
'use server';

import { cookies } from 'next/headers';

// 이 파일의 함수들은 브라우저가 부르지만 몸통은 서버에서만 돈다.
// 폼이 제출되면 Next 가 여기까지 값을 실어 나른다.
export async function signIn(formData: FormData) {
  const username = formData.get('username');

  if (typeof username !== 'string' || username === '') {
    return;
  }

  // httpOnly 라 브라우저 자바스크립트는 이 값을 못 읽는다. 서버만 본다.
  (await cookies()).set('me', username, {
    httpOnly: true,
    path: '/',
    maxAge: 60 * 60 * 24,
  });
}

export async function signOut() {
  (await cookies()).delete('me');
}

// apps/web-next/app/components/SignInForm.tsx
import { cookies } from 'next/headers';
import { signIn, signOut } from '@/app/actions/session';

// 지시어가 없다. 서버 컴포넌트다 — 그런데 폼이 있고 버튼이 동작한다.
// 쿠키를 읽으니 이 조각은 요청 때 채워진다.
export async function SignInForm() {
  const me = (await cookies()).get('me')?.value;

  if (me !== undefined) {
    return (
      <form action={signOut} className="ml-2 flex items-center gap-2">
        <span className="text-black/60">@{me}</span>
        <button type="submit" className="rounded border border-black/15 px-2 py-1">
          나가기
        </button>
      </form>
    );
  }

  // 어느 버튼을 눌렀는지는 name/value 로 함께 실려 간다.
  return (
    <form action={signIn} className="ml-2 flex items-center gap-2">
      <button
        type="submit"
        name="username"
        value="jaehoon"
        className="rounded border border-black/15 px-2 py-1"
      >
        재훈으로 보기
      </button>
      <button
        type="submit"
        name="username"
        value="minji"
        className="rounded border border-black/15 px-2 py-1"
      >
        민지로 보기
      </button>
    </form>
  );
}

// apps/web-next/app/components/HeaderNav.tsx
// children 으로 받은 것은 이 파일이 import 한 게 아니라 밖에서 만들어져 온다.
// 그래서 이 안에 서버 조각을 끼워 넣을 수 있다 — D-4 에서 본 그 구멍이다.
export function HeaderNav({ children }: { children?: ReactNode }) {

// apps/web-next/app/layout.tsx
            <Suspense fallback={<div className="mx-auto h-14 max-w-3xl" />}>
              {/* 로그인 칸은 쿠키를 읽는 서버 조각이다. 클라이언트 머리말 안에
                  children 으로 끼워 넣는다 — 경계를 넘어가지 않는다. */}
              <HeaderNav>
                <SignInForm />
              </HeaderNav>
            </Suspense>

<form action="" encType="multipart/form-data" method="POST">
  <input type="hidden" name="$ACTION_ID_40e4cbf2b7df5e2e9f3f7a912205f3ad51cacacedf"/>
  <button type="submit" value="jaehoon" name="username">재훈으로 보기</button>
  <button type="submit" value="minji" name="username">민지로 보기</button>
</form>

 브라우저                                    서버
    │                                         │
    │  POST /                                 │
    │  $ACTION_ID_40e4cb...                   │
    │  username=minji         ───────────>    │
    │                                         │   아 이 함수구나
    │                                         │   signIn(formData) 실행
    │                                         │   쿠키를 심는다
    │                                         │   화면을 다시 그린다
    │    <───────────  Set-Cookie + 새 화면   │
    │                                         │

curl -s http://localhost:3000/ | grep -o '\$ACTION_ID_[a-f0-9]*'

curl -s -D- -X POST http://localhost:3000/ \
  -F '$ACTION_ID_여기에_여러분_값=' \
  -F 'username=minji' | head -20

HTTP/1.1 200 OK
Set-Cookie: me=minji; Path=/; Max-Age=86400; HttpOnly

// apps/api-stub/server.mjs
  // 팔로우 — 누른 사람이 누구인지를 헤더로 받는다. 없으면 거절한다.
  // 진짜 서비스라면 세션이나 토큰을 보겠지만, 여기서는 "서버가 직접 확인한다" 는
  // 모양만 같으면 된다. 토큰 발급은 다른 시간에 다룬다.
  {
    method: 'POST',
    match: (path) => /^\/api\/users\/[^/]+\/follow$/.test(path),
    handle: async (req, res, path) => {
      const actor = req.headers['x-actor'];
      if (typeof actor !== 'string' || findUser(actor) === undefined) {
        return fail(res, 401, '로그인이 필요합니다');
      }

      const target = decodeURIComponent(path.split('/').at(-2));
      if (!posts.some((it) => it.username === target)) {
        return fail(res, 404, '그런 사람이 없습니다');
      }
      if (target === actor) {
        return fail(res, 400, '자기 자신은 팔로우할 수 없습니다');
      }
      // ... 팔로우 상태를 뒤집고 팔로워 수를 증감시킨다

      ok(res, { username: target, following: nowFollowing, followerCount: followersOf(target) });
    },
  },

 헤더 없이                  401  로그인이 필요합니다
 X-Actor: nobody           401  로그인이 필요합니다
 X-Actor: minji  -> minji  400  자기 자신은 팔로우할 수 없습니다
 X-Actor: jaehoon -> zzzzz 404  그런 사람이 없습니다
 X-Actor: jaehoon -> minji 200  {"following":true,"followerCount":8501}

// apps/web-next/app/actions/follow.ts
'use server';

import { cookies } from 'next/headers';

const API_BASE = 'http://localhost:8090/api';

export type FollowState = {
  /** 아직 눌러본 적이 없으면 null */
  following: boolean | null;
  message: string | null;
};

/**
 * 폼에서 받을 값이 없어서 formData 인자는 아예 안 적었다.
 * 대신 누구를 팔로우하는지는 호출부에서 미리 묶어 보낸다.
 */
export async function follow(username: string, previous: FollowState): Promise<FollowState> {
  // 누가 눌렀는지는 브라우저가 보내준 값이 아니라 서버가 직접 읽는다.
  const me = (await cookies()).get('me')?.value;

  if (me === undefined) {
    return { ...previous, message: '로그인이 필요해요' };
  }

  const response = await fetch(`${API_BASE}/users/${encodeURIComponent(username)}/follow`, {
    method: 'POST',
    headers: { 'X-Actor': me },
  });

  const envelope = await response.json();

  if (!response.ok || !envelope.success) {
    // 실패하면 알던 상태는 그대로 두고 사유만 얹는다.
    return { ...previous, message: envelope.message ?? '팔로우하지 못했어요' };
  }

  return { following: envelope.data.following, message: null };
}

// apps/web-next/app/components/FollowButton.tsx
'use client';

import { useActionState } from 'react';
import { follow, type FollowState } from '@/app/actions/follow';

const initial: FollowState = { following: null, message: null };

export function FollowButton({ username }: { username: string }) {
  // 서버 함수에 이름을 미리 묶어두면 나머지 인자는 React 가 채운다.
  const [state, formAction, pending] = useActionState(follow.bind(null, username), initial);

  return (
    <form action={formAction} className="mb-4">
      <button
        type="submit"
        disabled={pending}
        className="rounded border border-black/15 px-3 py-1 text-sm disabled:opacity-40"
      >
        {pending ? '보내는 중…' : state.following === true ? '팔로잉' : '팔로우'}
      </button>
      {state.message !== null && (
        <p aria-live="polite" className="mt-1 text-sm text-black/60">
          {state.message}
        </p>
      )}
    </form>
  );
}

 const [state, formAction, pending] = useActionState(액션, 초기값)
                │       │         └── 지금 실행 중인가 (true/false)
                │       └──────────── 폼의 action 에 넣을 것
                └──────────────────── 액션이 마지막으로 돌려준 값

 [api-stub] POST /api/users/minji/follow

 액션 실행 전   원본 8500  ·  화면 8500
 액션 실행 후   원본 8501  ·  화면 8500
 다시 봐도             ·  화면 8500
 또 봐도               ·  화면 8500

// apps/web-next/lib/api.ts
export async function fetchProfile(username: string): Promise<Profile> {
  'use cache';
  cacheLife('hours');
  // 이 칸에 이름표를 붙여둔다. 누군가 이 사람을 팔로우한 순간 이 이름으로 지목해 버릴 수 있게.
  cacheTag('profile', `profile:${username}`);
  return get<Profile>(`/users/${encodeURIComponent(username)}`);
}

// apps/web-next/app/actions/follow.ts
import { updateTag } from 'next/cache';

// ... 성공한 뒤에

  // 지난 시간에 붙여둔 이름표를 여기서 처음 부른다.
  // 이 이름이 달린 캐시 칸을 지금 당장 버려라 — 다음에 볼 사람은 새로 만든 것을 본다.
  updateTag(`profile:${username}`);

  return { following: envelope.data.following, message: null };

                    Step 3 (updateTag 없음)      Step 4 (updateTag 있음)
 액션 실행 전         원본 8500 · 화면 8500        원본 8501 · 화면 8501
 액션 실행 후         원본 8501                    원본 8500
 화면 1회                    8500                        8500
 화면 2회                    8500                        8500
 화면 3회                    8500                        8500

cacheTag('profile', `profile:${username}`);

 1. 민지 프로필과 재훈 프로필을 한 번씩 열어 둘 다 캐시에 담는다
 2. 앱을 안 거치고 API 서버에서 두 사람의 팔로워 수를 바꾼다
 3. 민지 프로필에서만 팔로우 버튼을 누른다
 4. 두 화면이 각각 어떻게 되는지 본다

 민지    원본 8501  ·  화면 8501     갱신됐다
 재훈    원본 1241  ·  화면 1240     낡은 채로 남았다

updateTag('profile');

 민지    원본 8500  ·  화면 8500     갱신됐다
 재훈    원본 1240  ·  화면 1240     같이 갱신됐다

 가는 이름표 (profile:minji)
   버리는 것: 민지 칸 하나
   대가:      우리가 지목한 것만 바뀐다. 다른 사람은 낡은 채로 남는다
   쓸 때:     무엇이 바뀌었는지 정확히 알 때

 굵은 이름표 (profile)
   버리는 것: 모든 사람의 프로필 칸
   대가:      멀쩡한 캐시까지 버려서 다시 만드는 비용이 든다
   쓸 때:     프로필 화면 구조 자체가 바뀌었을 때 (배포 직후 같은 경우)

// apps/web-next/app/api/profiles/revalidate/route.ts
import { revalidateTag } from 'next/cache';

// 파일 이름이 page 가 아니라 route 다. 그래서 이 주소는 화면을 안 그린다.
// 백엔드에서 사람 정보가 바뀌었을 때 우리에게 알려주라고 열어두는 문이다.
export async function POST(request: Request) {
  const username = new URL(request.url).searchParams.get('username');

  if (username === null) {
    return Response.json(
      { success: false, data: null, message: 'username 이 필요합니다' },
      { status: 400 },
    );
  }

  // 여기서는 updateTag 를 못 쓴다. 이 자리는 Server Action 이 아니다.
  revalidateTag(`profile:${username}`, 'max');

  return Response.json({ success: true, data: { username }, message: null });
}

 Route (app)
 ┌ ◐ /
 ├ ◐ /_not-found
 ├   /[username]
 │ └ ◐ /[username]
 ├ ƒ /api/profiles/revalidate
 └ ◐ /explore

 ◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content
 ƒ  (Dynamic)            server-rendered on demand

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/profiles/revalidate?username=minji

405

{"success":false,"data":null,"message":"username 이 필요합니다"} [400]

 1. 캐시를 채운다                       화면 8500 · 원본 8500
 2. 앱 밖에서 원본만 바꾼다              화면 8500 · 원본 8501
 3. POST /api/profiles/revalidate 호출   {"success":true,...}
 4. 바로 다시 본다   요청1              화면 8500   <-- 아직 옛 숫자!
                    요청2              화면 8501
                    요청3              화면 8501
                    요청4              화면 8501

 revalidateTag(태그, 'max')      updateTag(태그)
 아무도 안 기다린다                다음 사람이 기다린다
 한 명은 옛것을 본다               아무도 옛것을 안 본다
 남이 바꾼 것을 반영할 때           내가 바꾼 것을 내가 볼 때

 next build      exit 0     통과
 tsc --noEmit    0          통과

 500

⨯ Error: updateTag can only be called from within a Server Action.
  To invalidate cache tags in Route Handlers or other contexts,
  use revalidateTag instead.

 D-4   없는 사람 주소에 404 를 붙였다        401ms 를 내고 샀다
 D-5   캐시를 켰더니 200 으로 되돌아갔다      스위치 하나에 되팔렸다
 D-6   껍데기를 다 넓혔는데도 200 이었다      화면 안에서는 못 되찾는다
 D-7   ?

// apps/web-next/proxy.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const API_BASE = 'http://localhost:8090/api';

// 이 파일은 app 폴더 밖, 프로젝트 뿌리에 둔다.
// 요청이 우리 앱에 도착했지만 아직 아무것도 안 그려진 순간에 끼어든다.
// 여기서는 아직 한 글자도 안 나갔으니 상태 코드를 우리가 정할 수 있다.
export async function proxy(request: NextRequest) {
  const username = request.nextUrl.pathname.slice(1);

  const response = await fetch(`${API_BASE}/users/${encodeURIComponent(username)}`);

  if (response.status === 404) {
    // 주소는 그대로 두고 404 화면을 그리게 한다. 상태 코드는 우리가 얹는다.
    return NextResponse.rewrite(new URL('/_not-found', request.url), { status: 404 });
  }

  return NextResponse.next();
}

export const config = {
  // 프로필로 갈 수 있는 주소만 본다. 나머지는 아예 안 거친다.
  matcher: ['/((?!api|_next|favicon.ico|explore).+)'],
};

 /            200
 /explore     200
 /jaehoon     200
 /minji       200
 /zzzzz       404      <-- 되찾았다
 /a/b/c       404

 ƒ Proxy (Middleware)

 x-middleware-rewrite: /_not-found

npx @next/codemod@canary middleware-to-proxy .

              proxy 없을 때        proxy 있을 때
 /            2 ~ 4 ms             2 ~ 3 ms
 /explore     2 ~ 5 ms             1 ~ 2 ms
 /jaehoon     2 ~ 6 ms             404 ~ 406 ms
 /zzzzz       2 ms (200)           404 ms (404)

 GET  /api/users/minji            <-- proxy 의 존재 확인
 POST /api/users/minji/follow     <-- 진짜 할 일
 GET  /api/posts?username=minji   <-- 화면 다시 그리기
 GET  /api/users/minji/tags       <-- 화면 다시 그리기
 GET  /api/users/minji            <-- updateTag 로 버린 것 다시 만들기

// apps/web-next/proxy.ts
export async function proxy(request: NextRequest) {
  // 화면을 달라는 요청에만 확인이 필요하다.
  // 폼을 제출하면 같은 주소로 POST 가 오는데, 거기까지 물어볼 이유는 없다.
  if (request.method !== 'GET') {
    return NextResponse.next();
  }

  const username = request.nextUrl.pathname.slice(1);
  // ... 나머지는 그대로

                        고치기 전    고친 뒤
 팔로우 한 번에 나가는
 "이 사람 있나요" 요청      3 건       2 건

 /zzzzz                    404        404      그대로
 /a/b/c                    404        404      그대로
 /jaehoon 첫 바이트        406ms      406ms    그대로

 얻는 것    없는 주소가 정확한 상태 코드로 답한다
            검색 엔진·통계 도구·감시 시스템이 제대로 읽는다

 내는 것    프로필 화면 전부의 첫 바이트가 늦어진다
            우리 경우 약 400ms (API 서버가 답하는 시간)

FOLLOW_FAIL_EVERY=2 API_STUB_LOG=1 node apps/api-stub/server.mjs

matcher: ['/((?!api|_next|favicon.ico).+)'],