Function postFreebuffSession

web/src/app/api/v1/freebuff/session/_handlers.ts:222–268

(
  req: NextRequest,
  deps: FreebuffSessionDeps,
)

/** POST /api/v1/freebuff/session — join queue / take over as this instance. */
export async function postFreebuffSession(
  req: NextRequest,
  deps: FreebuffSessionDeps,
): Promise<NextResponse> {
  const auth = await resolveUser(req, deps)
  if ('error' in auth) return auth.error

  const countryAccess = await getCountryAccess(auth.userId, req, deps)
  logCountryAccess('POST', auth.userId, countryAccess, deps)
  if (shouldHardBlockFreeModeAccess(countryAccess)) {
    await endSessionForHardBlock(auth, deps)
    return hardBlockedResponse(countryAccess)
  }
  const accessTier = getFreeModeAccessTier(countryAccess)

  const requestedModel = req.headers.get(FREEBUFF_MODEL_HEADER) ?? ''

  try {
    const state = await requestSession({
      userId: auth.userId,
      userEmail: auth.userEmail,
      userBanned: auth.userBanned,
      model: requestedModel,
      accessTier,
      countryAccess: toSessionCountryAccess(countryAccess),
      deps: deps.sessionDeps,
    })
    // model_locked / model_unavailable are 409 so they're distinguishable
    // from normal queued/active responses on the client. banned is a 403
    // (terminal, mirrors country_blocked) so older CLIs that don't know the
    // status fall into their `!resp.ok` error path and back off instead of
    // tight-polling on the unrecognized 200 body. rate_limited uses 429 for
    // the same reason as banned — older CLIs back off, newer CLIs parse the
    // structured body.
    const status =
      state.status === 'model_locked' || state.status === 'model_unavailable'
        ? 409
        : state.status === 'banned'
          ? 403
          : state.status === 'rate_limited'
            ? 429
            : 200
    return NextResponse.json(state, { status })
  } catch (error) {
    return serverError(deps, 'POST', auth.userId, error)
  }
}

/** GET /api/v1/freebuff/session — read current state without mutation. The
 *  caller's instance id (via X-Freebuff-Instance-Id) is used to detect